#' Estimation of Proportions

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Estimate the proportion of responders within a studied population.

#'

#' @inheritParams prop_strat_wilson

#' @inheritParams argument_convention

#' @param .stats (`character`)\cr statistics to select for the table. Run `get_stats("estimate_proportion")`

#'   to see available statistics for this function.

#' @param method (`string`)\cr the method used to construct the confidence interval

#'   for proportion of successful outcomes; one of `waldcc`, `wald`, `clopper-pearson`,

#'   `wilson`, `wilsonc`, `strat_wilson`, `strat_wilsonc`, `agresti-coull` or `jeffreys`.

#' @param long (`flag`)\cr a long description is required.

#'

#' @seealso [h_proportions]

#'

#' @name estimate_proportions

#' @order 1

NULL

#' @describeIn estimate_proportions Statistics function estimating a

#'   proportion along with its confidence interval.

#'

#' @param df (`logical` or `data.frame`)\cr if only a logical vector is used,

#'   it indicates whether each subject is a responder or not. `TRUE` represents

#'   a successful outcome. If a `data.frame` is provided, also the `strata` variable

#'   names must be provided in `variables` as a list element with the strata strings.

#'   In the case of `data.frame`, the logical vector of responses must be indicated as a

#'   variable name in `.var`.

#'

#' @return

#' * `s_proportion()` returns statistics `n_prop` (`n` and proportion) and `prop_ci` (proportion CI) for a

#'   given variable.

#'

#' @examples

#' # Case with only logical vector.

#' rsp_v <- c(1, 0, 1, 0, 1, 1, 0, 0)

#' s_proportion(rsp_v)

#'

#' # Example for Stratified Wilson CI

#' nex <- 100 # Number of example rows

#' dta <- data.frame(

#'   "rsp" = sample(c(TRUE, FALSE), nex, TRUE),

#'   "grp" = sample(c("A", "B"), nex, TRUE),

#'   "f1" = sample(c("a1", "a2"), nex, TRUE),

#'   "f2" = sample(c("x", "y", "z"), nex, TRUE),

#'   stringsAsFactors = TRUE

#' )

#'

#' s_proportion(

#'   df = dta,

#'   .var = "rsp",

#'   variables = list(strata = c("f1", "f2")),

#'   conf_level = 0.90,

#'   method = "strat_wilson"

#' )

#'

#' @export

s_proportion <- function(df,

                         .var,

                         conf_level = 0.95,

                         method = c(

                           "waldcc", "wald", "clopper-pearson",

                           "wilson", "wilsonc", "strat_wilson", "strat_wilsonc",

                           "agresti-coull", "jeffreys"

                         ),

                         weights = NULL,

                         max_iterations = 50,

                         variables = list(strata = NULL),

                         long = FALSE) {

    # Checks for strata

    # Pushing down checks to prop_strat_wilson

  }

  } else {

  }

  )

    )

  )

}

#' @describeIn estimate_proportions Formatted analysis function which is used as `afun`

#'   in `estimate_proportion()`.

#'

#' @return

#' * `a_proportion()` returns the corresponding list with formatted [rtables::CellValue()].

#'

#' @export

a_proportion <- make_afun(

  s_proportion,

  .formats = c(n_prop = "xx (xx.x%)", prop_ci = "(xx.x, xx.x)")

)

#' @describeIn estimate_proportions Layout-creating function which can take statistics function arguments

#'   and additional format arguments. This function is a wrapper for [rtables::analyze()].

#'

#' @return

#' * `estimate_proportion()` returns a layout object suitable for passing to further layouting functions,

#'   or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing

#'   the statistics from `s_proportion()` to the table layout.

#'

#' @examples

#' dta_test <- data.frame(

#'   USUBJID = paste0("S", 1:12),

#'   ARM     = rep(LETTERS[1:3], each = 4),

#'   AVAL    = c(A = c(1, 1, 1, 1), B = c(0, 0, 1, 1), C = c(0, 0, 0, 0))

#' )

#'

#' basic_table() %>%

#'   split_cols_by("ARM") %>%

#'   estimate_proportion(vars = "AVAL") %>%

#'   build_table(df = dta_test)

#'

#' @export

#' @order 2

estimate_proportion <- function(lyt,

                                vars,

                                conf_level = 0.95,

                                method = c(

                                  "waldcc", "wald", "clopper-pearson",

                                  "wilson", "wilsonc", "strat_wilson", "strat_wilsonc",

                                  "agresti-coull", "jeffreys"

                                ),

                                weights = NULL,

                                max_iterations = 50,

                                variables = list(strata = NULL),

                                long = FALSE,

                                na_str = default_na_str(),

                                nested = TRUE,

                                ...,

                                show_labels = "hidden",

                                table_names = vars,

                                .stats = NULL,

                                .formats = NULL,

                                .labels = NULL,

                                .indent_mods = NULL) {

  )

  )

  )

}

#' Helper Functions for Calculating Proportion Confidence Intervals

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Functions to calculate different proportion confidence intervals for use in [estimate_proportion()].

#'

#' @inheritParams argument_convention

#' @inheritParams estimate_proportions

#'

#' @return Confidence interval of a proportion.

#'

#' @seealso [estimate_proportions], descriptive function [d_proportion()],

#'  and helper functions [strata_normal_quantile()] and [update_weights_strat_wilson()].

#'

#' @name h_proportions

NULL

#' @describeIn h_proportions Calculates the Wilson interval by calling [stats::prop.test()].

#'  Also referred to as Wilson score interval.

#'

#' @examples

#' rsp <- c(

#'   TRUE, TRUE, TRUE, TRUE, TRUE,

#'   FALSE, FALSE, FALSE, FALSE, FALSE

#' )

#' prop_wilson(rsp, conf_level = 0.9)

#'

#' @export

prop_wilson <- function(rsp, conf_level, correct = FALSE) {

  )

}

#' @describeIn h_proportions Calculates the stratified Wilson confidence

#'   interval for unequal proportions as described in \insertCite{Yan2010-jt;textual}{tern}

#'

#' @param strata (`factor`)\cr variable with one level per stratum and same length as `rsp`.

#' @param weights (`numeric` or `NULL`)\cr weights for each level of the strata. If `NULL`, they are

#'   estimated using the iterative algorithm proposed in \insertCite{Yan2010-jt;textual}{tern} that

#'   minimizes the weighted squared length of the confidence interval.

#' @param max_iterations (`count`)\cr maximum number of iterations for the iterative procedure used

#'   to find estimates of optimal weights.

#' @param correct (`flag`)\cr include the continuity correction. For further information, see for example

#'   [stats::prop.test()].

#'

#' @references

#' \insertRef{Yan2010-jt}{tern}

#'

#' @examples

#' # Stratified Wilson confidence interval with unequal probabilities

#'

#' set.seed(1)

#' rsp <- sample(c(TRUE, FALSE), 100, TRUE)

#' strata_data <- data.frame(

#'   "f1" = sample(c("a", "b"), 100, TRUE),

#'   "f2" = sample(c("x", "y", "z"), 100, TRUE),

#'   stringsAsFactors = TRUE

#' )

#' strata <- interaction(strata_data)

#' n_strata <- ncol(table(rsp, strata)) # Number of strata

#'

#' prop_strat_wilson(

#'   rsp = rsp, strata = strata,

#'   conf_level = 0.90

#' )

#'

#' # Not automatic setting of weights

#' prop_strat_wilson(

#'   rsp = rsp, strata = strata,

#'   weights = rep(1 / n_strata, n_strata),

#'   conf_level = 0.90

#' )

#'

#' @export

prop_strat_wilson <- function(rsp,

                              strata,

                              weights = NULL,

                              conf_level = 0.95,

                              max_iterations = NULL,

                              correct = FALSE) {

  # Checking the weights and maximum number of iterations.

    # Iteration parameters

  }

  # Iterative setting of weights if they were not set externally

  } else {

  }

      # Classic Wilson's confidence interval

    },

  )

  # Return values

      ),

    )

  } else {

      )

    )

  }

}

#' @describeIn h_proportions Calculates the Clopper-Pearson interval by calling [stats::binom.test()].

#'   Also referred to as the `exact` method.

#'

#' @examples

#' prop_clopper_pearson(rsp, conf_level = .95)

#'

#' @export

prop_clopper_pearson <- function(rsp,

                                 conf_level) {

  )

}

#' @describeIn h_proportions Calculates the Wald interval by following the usual textbook definition

#'   for a single proportion confidence interval using the normal approximation.

#'

#' @param correct (`flag`)\cr apply continuity correction.

#'

#' @examples

#' prop_wald(rsp, conf_level = 0.95)

#' prop_wald(rsp, conf_level = 0.95, correct = TRUE)

#'

#' @export

prop_wald <- function(rsp, conf_level, correct = FALSE) {

}

#' @describeIn h_proportions Calculates the `Agresti-Coull` interval (created by `Alan Agresti` and `Brent Coull`) by

#'   (for 95% CI) adding two successes and two failures to the data and then using the Wald formula to construct a CI.

#'

#' @examples

#' prop_agresti_coull(rsp, conf_level = 0.95)

#'

#' @export

prop_agresti_coull <- function(rsp, conf_level) {

  # Add here both z^2 / 2 successes and failures.

  # Then proceed as with the Wald interval.

}

#' @describeIn h_proportions Calculates the Jeffreys interval, an equal-tailed interval based on the

#'   non-informative Jeffreys prior for a binomial proportion.

#'

#' @examples

#' prop_jeffreys(rsp, conf_level = 0.95)

#'

#' @export

prop_jeffreys <- function(rsp,

                          conf_level) {

  )

  )

}

#' Description of the Proportion Summary

#'

#' @description `r lifecycle::badge("stable")`

#'

#' This is a helper function that describes the analysis in [s_proportion()].

#'

#' @inheritParams s_proportion

#' @param long (`flag`)\cr whether a long or a short (default) description is required.

#'

#' @return String describing the analysis.

#'

#' @export

d_proportion <- function(conf_level,

                         method,

                         long = FALSE) {

  )

}

#' Helper Function for the Estimation of Stratified Quantiles

#'

#' @description `r lifecycle::badge("stable")`

#'

#' This function wraps the estimation of stratified percentiles when we assume

#' the approximation for large numbers. This is necessary only in the case

#' proportions for each strata are unequal.

#'

#' @inheritParams argument_convention

#' @inheritParams prop_strat_wilson

#'

#' @return Stratified quantile.

#'

#' @seealso [prop_strat_wilson()]

#'

#' @examples

#' strata_data <- table(data.frame(

#'   "f1" = sample(c(TRUE, FALSE), 100, TRUE),

#'   "f2" = sample(c("x", "y", "z"), 100, TRUE),

#'   stringsAsFactors = TRUE

#' ))

#' ns <- colSums(strata_data)

#' ests <- strata_data["TRUE", ] / ns

#' vars <- ests * (1 - ests) / ns

#' weights <- rep(1 / length(ns), length(ns))

#'

#' strata_normal_quantile(vars, weights, 0.95)

#'

#' @export

strata_normal_quantile <- function(vars, weights, conf_level) {

  # Stratified quantile

}

#' Helper Function for the Estimation of Weights for `prop_strat_wilson`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' This function wraps the iteration procedure that allows you to estimate

#' the weights for each proportional strata. This assumes to minimize the

#' weighted squared length of the confidence interval.

#'

#' @inheritParams prop_strat_wilson

#' @param vars (`numeric`)\cr normalized proportions for each strata.

#' @param strata_qnorm (`numeric`)\cr initial estimation with identical weights of the quantiles.

#' @param initial_weights (`numeric`)\cr initial weights used to calculate `strata_qnorm`. This can

#'   be optimized in the future if we need to estimate better initial weights.

#' @param n_per_strata (`numeric`)\cr number of elements in each strata.

#' @param max_iterations (`count`)\cr maximum number of iterations to be tried. Convergence is always checked.

#' @param tol (`number`)\cr tolerance threshold for convergence.

#'

#' @return A `list` of 3 elements: `n_it`, `weights`, and `diff_v`.

#'

#' @seealso For references and details see [prop_strat_wilson()].

#'

#' @examples

#' vs <- c(0.011, 0.013, 0.012, 0.014, 0.017, 0.018)

#' sq <- 0.674

#' ws <- rep(1 / length(vs), length(vs))

#' ns <- c(22, 18, 17, 17, 14, 12)

#'

#' update_weights_strat_wilson(vs, sq, ws, ns, 100, 0.95, 0.001)

#'

#' @export

update_weights_strat_wilson <- function(vars,

                                        strata_qnorm,

                                        initial_weights,

                                        n_per_strata,

                                        max_iterations = 50,

                                        conf_level = 0.95,

                                        tol = 0.001) {

  }

  }

  )

}

#' Helper Functions for Multivariate Logistic Regression

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Helper functions used in calculations for logistic regression.

#'

#' @inheritParams argument_convention

#' @param fit_glm (`glm`)\cr logistic regression model fitted by [stats::glm()] with "binomial" family.

#'   Limited functionality is also available for conditional logistic regression models fitted by

#'   [survival::clogit()], currently this is used only by [extract_rsp_biomarkers()].

#' @param x (`string` or `character`)\cr a variable or interaction term in `fit_glm` (depending on the

#'   helper function).

#'

#' @examples

#' library(dplyr)

#' library(broom)

#'

#' adrs_f <- tern_ex_adrs %>%

#'   filter(PARAMCD == "BESRSPI") %>%

#'   filter(RACE %in% c("ASIAN", "WHITE", "BLACK OR AFRICAN AMERICAN")) %>%

#'   mutate(

#'     Response = case_when(AVALC %in% c("PR", "CR") ~ 1, TRUE ~ 0),

#'     RACE = factor(RACE),

#'     SEX = factor(SEX)

#'   )

#' formatters::var_labels(adrs_f) <- c(formatters::var_labels(tern_ex_adrs), Response = "Response")

#' mod1 <- fit_logistic(

#'   data = adrs_f,

#'   variables = list(

#'     response = "Response",

#'     arm = "ARMCD",

#'     covariates = c("AGE", "RACE")

#'   )

#' )

#' mod2 <- fit_logistic(

#'   data = adrs_f,

#'   variables = list(

#'     response = "Response",

#'     arm = "ARMCD",

#'     covariates = c("AGE", "RACE"),

#'     interaction = "AGE"

#'   )

#' )

#'

#' @name h_logistic_regression

NULL

#' @describeIn h_logistic_regression Helper function to extract interaction variable names from a fitted

#'   model assuming only one interaction term.

#'

#' @return Vector of names of interaction variables.

#'

#' @export

h_get_interaction_vars <- function(fit_glm) {

}

#' @describeIn h_logistic_regression Helper function to get the right coefficient name from the

#'   interaction variable names and the given levels. The main value here is that the order

#'   of first and second variable is checked in the `interaction_vars` input.

#'

#' @param interaction_vars (`character` of length 2)\cr interaction variable names.

#' @param first_var_with_level (`character` of length 2)\cr the first variable name with

#'   the interaction level.

#' @param second_var_with_level (`character` of length 2)\cr the second variable name with

#'   the interaction level.

#'

#' @return Name of coefficient.

#'

#' @export

h_interaction_coef_name <- function(interaction_vars,

                                    first_var_with_level,

                                    second_var_with_level) {

  }

}

#' @describeIn h_logistic_regression Helper function to calculate the odds ratio estimates

#'   for the case when both the odds ratio and the interaction variable are categorical.

#'

#' @param odds_ratio_var (`string`)\cr the odds ratio variable.

#' @param interaction_var (`string`)\cr the interaction variable.

#'

#' @return Odds ratio.

#'

#' @export

h_or_cat_interaction <- function(odds_ratio_var,

                                 interaction_var,

                                 fit_glm,

                                 conf_level = 0.95) {

        )

        )

      }

      } else {

      }

    }

  }

}

#' @describeIn h_logistic_regression Helper function to calculate the odds ratio estimates

#'   for the case when either the odds ratio or the interaction variable is continuous.

#'

#' @param at (`NULL` or `numeric`)\cr optional values for the interaction variable. Otherwise

#'   the median is used.

#'

#' @return Odds ratio.

#'

#' @note We don't provide a function for the case when both variables are continuous because

#'   this does not arise in this table, as the treatment arm variable will always be involved

#'   and categorical.

#'

#' @export

h_or_cont_interaction <- function(odds_ratio_var,

                                  interaction_var,

                                  fit_glm,

                                  at = NULL,

                                  conf_level = 0.95) {

  }

    }

          )

          )

        }

        } else {

        }

      }

    }

  } else {

        )

        )

      }

      } else {

      }

    }

  }

}

#' @describeIn h_logistic_regression Helper function to calculate the odds ratio estimates

#'   in case of an interaction. This is a wrapper for [h_or_cont_interaction()] and

#'   [h_or_cat_interaction()].

#'

#' @return Odds ratio.

#'

#' @export

h_or_interaction <- function(odds_ratio_var,

                             interaction_var,

                             fit_glm,

                             at = NULL,

                             conf_level = 0.95) {

    )

    )

  } else {

  }

}

#' @describeIn h_logistic_regression Helper function to construct term labels from simple terms and the table

#'   of numbers of patients.

#'

#' @param terms (`character`)\cr simple terms.

#' @param table (`table`)\cr table containing numbers for terms.

#'

#' @return Term labels containing numbers of patients.

#'

#' @export

h_simple_term_labels <- function(terms,

                                 table) {

}

#' @describeIn h_logistic_regression Helper function to construct term labels from interaction terms and the table

#'   of numbers of patients.

#'

#' @param terms1 (`character`)\cr terms for first dimension (rows).

#' @param terms2 (`character`)\cr terms for second dimension (rows).

#' @param any (`flag`)\cr whether any of `term1` and `term2` can be fulfilled to count the

#'   number of patients. In that case they can only be scalar (strings).

#'

#' @return Term labels containing numbers of patients.

#'

#' @export

h_interaction_term_labels <- function(terms1,

                                      terms2,

                                      table,

                                      any = FALSE) {

      # Note that we double count in the initial sum the cell [terms1, terms2], therefore subtract.

    )

  } else {

  }

}

#' @describeIn h_logistic_regression Helper function to tabulate the main effect

#'   results of a (conditional) logistic regression model.

#'

#' @return Tabulated main effect results from a logistic regression model.

#'

#' @examples

#' h_glm_simple_term_extract("AGE", mod1)

#' h_glm_simple_term_extract("ARMCD", mod1)

#'

#' @export

h_glm_simple_term_extract <- function(x, fit_glm) {

  } else {

  }

  # Make sure x is not an interaction term.

    } else {

      # We just fill in here with the `term` itself as we don't have the data available.

    }

  } else {

    # The reason is that we don't have the original data set in the `clogit` object

    # and therefore cannot determine the `x_numbers` here.

    )

    }

  }

  } else {

  }

  )]

}

#' @describeIn h_logistic_regression Helper function to tabulate the interaction term

#'   results of a logistic regression model.

#'

#' @return Tabulated interaction term results from a logistic regression model.

#'

#' @examples

#' h_glm_interaction_extract("ARMCD:AGE", mod2)

#'

#' @export

h_glm_interaction_extract <- function(x, fit_glm) {

  # Only take two-way interaction

  # Only consider simple case: first variable in interaction is arm, a categorical variable

    )

    )

  }

  )

    "*",

  )

  )]

}

#' @describeIn h_logistic_regression Helper function to tabulate the interaction

#'   results of a logistic regression model. This basically is a wrapper for

#'   [h_or_interaction()] and [h_glm_simple_term_extract()] which puts the results

#'   in the right data frame format.

#'

#' @return A `data.frame` of tabulated interaction term results from a logistic regression model.

#'

#' @examples

#' h_glm_inter_term_extract("AGE", "ARMCD", mod2)

#'

#' @export

h_glm_inter_term_extract <- function(odds_ratio_var,

                                     interaction_var,

                                     fit_glm,

                                     ...) {

  # First obtain the main effects.

  # Then we get the odds ratio estimates and put into df form.

    # Numeric OR variable case.

        })

      ))

    }

    )

  } else {

    # Categorical OR variable case.

        })

      ))

    }

    )

  }

  )

}

#' @describeIn h_logistic_regression Helper function to tabulate the results including

#'   odds ratios and confidence intervals of simple terms.

#'

#' @return Tabulated statistics for the given variable(s) from the logistic regression model.

#'

#' @examples

#' h_logistic_simple_terms("AGE", mod1)

#'

#' @export

h_logistic_simple_terms <- function(x, fit_glm, conf_level = 0.95) {

  }

    # Make sure any item in x is not part of interaction term

  }

}

#' @describeIn h_logistic_regression Helper function to tabulate the results including

#'   odds ratios and confidence intervals of interaction terms.

#'

#' @return Tabulated statistics for the given variable(s) from the logistic regression model.

#'

#' @examples

#' h_logistic_inter_terms(c("RACE", "AGE", "ARMCD", "AGE:ARMCD"), mod2)

#'

#' @export

h_logistic_inter_terms <- function(x,

                                   fit_glm,

                                   conf_level = 0.95,

                                   at = NULL) {

  # Find out the interaction variables and interaction term.

  # For the non-interaction vars we need the standard stuff.

  # Now the interaction term itself.

  # Interaction stuff.

  )

  )

  # Now just combine everything in one data frame.

  )

  )

    )

  }

}

#' Control Function for Subgroup Treatment Effect Pattern (STEP) Calculations

#'

#' @description `r lifecycle::badge("stable")`

#'

#' This is an auxiliary function for controlling arguments for STEP calculations.

#'

#' @param biomarker (`numeric` or `NULL`)\cr optional provision of the numeric biomarker variable, which

#'   could be used to infer `bandwidth`, see below.

#' @param use_percentile (`flag`)\cr if `TRUE`, the running windows are created according to

#'   quantiles rather than actual values, i.e. the bandwidth refers to the percentage of data

#'   covered in each window. Suggest `TRUE` if the biomarker variable is not uniformly

#'   distributed.

#' @param bandwidth (`number` or `NULL`)\cr indicating the bandwidth of each window.

#'   Depending on the argument `use_percentile`, it can be either the length of actual-value

#'   windows on the real biomarker scale, or percentage windows.

#'   If `use_percentile = TRUE`, it should be a number between 0 and 1.

#'   If `NULL`, treat the bandwidth to be infinity, which means only one global model will be fitted.

#'   By default, `0.25` is used for percentage windows and one quarter of the range of the `biomarker`

#'   variable for actual-value windows.

#' @param degree (`count`)\cr the degree of polynomial function of the biomarker as an interaction term

#'   with the treatment arm fitted at each window. If 0 (default), then the biomarker variable

#'   is not included in the model fitted in each biomarker window.

#' @param num_points (`count`)\cr the number of points at which the hazard ratios are estimated. The

#'   smallest number is 2.

#'

#' @return A list of components with the same names as the arguments, except `biomarker` which is

#'   just used to calculate the `bandwidth` in case that actual biomarker windows are requested.

#'

#' @examples

#' # Provide biomarker values and request actual values to be used,

#' # so that bandwidth is chosen from range.

#' control_step(biomarker = 1:10, use_percentile = FALSE)

#'

#' # Use a global model with quadratic biomarker interaction term.

#' control_step(bandwidth = NULL, degree = 2)

#'

#' # Reduce number of points to be used.

#' control_step(num_points = 10)

#'

#' @export

control_step <- function(biomarker = NULL,

                         use_percentile = TRUE,

                         bandwidth,

                         degree = 0L,

                         num_points = 39L) {

    # Infer bandwidth

    } else {

    }

  } else {

    # Check bandwidth

      } else {

      }

    }

  }

  )

}

#' Create a forest plot from an `rtable`

#'

#' Given a [rtables::rtable()] object with at least one column with a single value and one column with 2

#' values, converts table to a [ggplot2::ggplot()] object and generates an accompanying forest plot. The

#' table and forest plot are printed side-by-side.

#'

#' @description `r lifecycle::badge("stable")`

#'

#' @inheritParams rtable2gg

#' @inheritParams argument_convention

#' @param tbl (`rtable`)\cr table with at least one column with a single value and one column with 2 values.

#' @param col_x (`integer`)\cr column index with estimator. By default tries to get this from

#'   `tbl` attribute `col_x`, otherwise needs to be manually specified. If `NULL`, points will be excluded

#'   from forest plot.

#' @param col_ci (`integer`)\cr column index with confidence intervals. By default tries to get this from

#'   `tbl` attribute `col_ci`, otherwise needs to be manually specified. If `NULL`, lines will be excluded

#'   from forest plot.

#' @param vline (`numeric`)\cr x coordinate for vertical line, if `NULL` then the line is omitted.

#' @param forest_header (`character`, length 2)\cr text displayed to the left and right of `vline`, respectively.

#'   If `vline = NULL` then `forest_header` is not printed. By default tries to get this from `tbl` attribute

#'   `forest_header`. If `NULL`, defaults will be extracted from the table if possible, and set to

#'   `"Comparison\nBetter"` and `"Treatment\nBetter"` if not.

#' @param xlim (`numeric`)\cr limits for x axis.

#' @param logx (`flag`)\cr show the x-values on logarithm scale.

#' @param x_at (`numeric`)\cr x-tick locations, if `NULL`, `x_at` is set to `vline` and both `xlim` values.

#' @param width_row_names `r lifecycle::badge("deprecated")` Please use the `lbl_col_padding` argument instead.

#' @param width_columns (`vector` of `numeric`)\cr a vector of column widths. Each element's position in

#'   `colwidths` corresponds to the column of `tbl` in the same position. If `NULL`, column widths are calculated

#'   according to maximum number of characters per column.

#' @param width_forest `r lifecycle::badge("deprecated")` Please use the `rel_width_forest` argument instead.

#' @param rel_width_forest (`proportion`)\cr proportion of total width to allocate to the forest plot. Relative

#'   width of table is then `1 - rel_width_forest`. If `as_list = TRUE`, this parameter is ignored.

#' @param font_size (`numeric`)\cr font size.

#' @param col_symbol_size (`integer`)\cr column index from `tbl` containing data to be used

#'   to determine relative size for estimator plot symbol. Typically, the symbol size is proportional

#'   to the sample size used to calculate the estimator. If `NULL`, the same symbol size is used for all subgroups.

#'   By default tries to get this from `tbl` attribute `col_symbol_size`, otherwise needs to be manually specified.